Crate leptos

About Leptos

Leptos is a full-stack framework for building web applications in Rust. You can use it to build

• single-page apps (SPAs) rendered entirely in the browser, using client-side routing and loading or mutating data via async requests to the server
• multi-page apps (MPAs) rendered on the server, managing navigation, data, and mutations via web-standard <a> and <form> tags
• progressively-enhanced single-page apps that are rendered on the server and then hydrated on the client, enhancing your <a> and <form> navigations and mutations seamlessly when WASM is available.

And you can do all three of these using the same Leptos code.

Take a look at the Leptos Book for a walkthrough of the framework. Join us on our Discord Channel to see what the community is building. Explore our Examples to see Leptos in action.

Learning by Example

If you want to see what Leptos is capable of, check out the examples:

• counter is the classic counter example, showing the basics of client-side rendering and reactive DOM updates
• counter_without_macros adapts the counter example to use the builder pattern for the UI and avoids other macros, instead showing the code that Leptos generates.
• counters introduces parent-child communication via contexts, and the <For/> component for efficient keyed list updates.
• counters_stable adapts the counters example to show how to use Leptos with stable Rust.
• error_boundary shows how to use Result types to handle errors.
• parent_child shows four different ways a parent component can communicate with a child, including passing a closure, context, and more
• fetch introduces Resources, which allow you to integrate arbitrary async code like an HTTP request within your reactive code.
• router shows how to use Leptos’s nested router to enable client-side navigation and route-specific, reactive data loading.
• slots shows how to use slots on components.
• counter_isomorphic shows different methods of interaction with a stateful server, including server functions, server actions, forms, and server-sent events (SSE).
• todomvc shows the basics of building an isomorphic web app. Both the server and the client import the same app code from the todomvc example. The server renders the app directly to an HTML string, and the client hydrates that HTML to make it interactive. You might also want to see how we use create_effect to serialize JSON to localStorage and reactively call DOM methods on references to elements.
• hackernews and hackernews_axum integrate calls to a real external REST API, routing, server-side rendering and hydration to create a fully-functional application that works as intended even before WASM has loaded and begun to run.
• todo_app_sqlite, todo_app_sqlite_axum, and todo_app_sqlite_viz show how to build a full-stack app using server functions and database connections.
• tailwind shows how to integrate TailwindCSS with cargo-leptos.

Details on how to run each example can be found in its README.

Quick Links

Here are links to the most important sections of the docs:

• Reactivity: the leptos_reactive overview, and more details in
  • signals: create_signal, ReadSignal, and WriteSignal (and create_rw_signal and RwSignal)
  • computations: create_memo and Memo
  • async interop: create_resource and Resource for loading data using async functions, and create_action and Action to mutate data or imperatively call async functions.
  • reactions: create_effect
• Templating/Views: the view macro
• Routing: the leptos_router crate
• Server Functions: the server macro, create_action, and create_server_action

Feature Flags

• nightly: On nightly Rust, enables the function-call syntax for signal getters and setters.
• csr Client-side rendering: Generate DOM nodes in the browser
• ssr Server-side rendering: Generate an HTML string (typically on the server)
• hydrate Hydration: use this to add interactivity to an SSRed Leptos app
• serde (Default) In SSR/hydrate mode, uses serde to serialize resources and send them from the server to the client.
• serde-lite In SSR/hydrate mode, uses serde-lite to serialize resources and send them from the server to the client.
• rkyv In SSR/hydrate mode, uses rkyv to serialize resources and send them from the server to the client.
• miniserde In SSR/hydrate mode, uses miniserde to serialize resources and send them from the server to the client.
• tracing Adds additional support for tracing to components.
• default-tls Use default native TLS support. (Only applies when using server functions with a non-WASM client like a desktop app.)
• rustls Use rustls. (Only applies when using server functions with a non-WASM client like a desktop app.)
• template_macro Enables the template! macro, which offers faster DOM node creation for some use cases in csr.

Important Note: You must enable one of csr, hydrate, or ssr to tell Leptos which mode your app is operating in. You should only enable one of these per build target, i.e., you should not have both hydrate and ssr enabled for your server binary, only ssr.

A Simple Counter

use leptos::*;

#[component]
pub fn SimpleCounter(cx: Scope, initial_value: i32) -> impl IntoView {
    // create a reactive signal with the initial value
    let (value, set_value) = create_signal(cx, initial_value);

    // create event handlers for our buttons
    // note that `value` and `set_value` are `Copy`, so it's super easy to move them into closures
    let clear = move |_| set_value.set(0);
    let decrement = move |_| set_value.update(|value| *value -= 1);
    let increment = move |_| set_value.update(|value| *value += 1);

    // this JSX is compiled to an HTML template string for performance
    view! {
        cx,
        <div>
            <button on:click=clear>"Clear"</button>
            <button on:click=decrement>"-1"</button>
            <span>"Value: " {move || value.get().to_string()} "!"</span>
            <button on:click=increment>"+1"</button>
        </div>
    }
}

Leptos is easy to use with Trunk (or with a simple wasm-bindgen setup):

#[component]
fn SimpleCounter(cx: Scope, initial_value: i32) -> impl IntoView {
    todo!()
}

pub fn main() {
    mount_to_body(|cx| view! { cx,  <SimpleCounter initial_value=3 /> })
}

Re-exports

• pub use server_fn::ServerFn as _;
• pub use leptos_config;
• pub use leptos_dom;
• pub use leptos_server;
• pub use server_fn;
• pub use typed_builder;

Modules

• error
  Types to make it easier to handle errors in your application.
• ev
  Types for all DOM events.
• html
  Exports types for working with HTML elements.
• math
  Exports types for working with MathML elements.
• nonce
  Utilities for exporting nonces to be used for a Content Security Policy.
• signal_prelude
  This prelude imports all signal types as well as all signal traits needed to use those types.
• ssr
  Utilities for server-side rendering HTML.
• suspense
  Types that handle asynchronous data loading via <Suspense/>.
• svg
  Exports types for working with SVG elements.

Macros

• debug_warn
  Uses println!()-style formatting to log warnings to the console (in the browser) or via eprintln!() (if not in the browser), but only if it’s a debug build.
• error
  Uses println!()-style formatting to log errors to the console (in the browser) or via eprintln!() (if not in the browser).
• log
  Uses println!()-style formatting to log something to the console (in the browser) or via println!() (if not in the browser).
• template
  The view macro uses RSX (like JSX, but Rust!) It follows most of the same rules as HTML, with the following differences:
• view
  The view macro uses RSX (like JSX, but Rust!) It follows most of the same rules as HTML, with the following differences:
• warn
  Uses println!()-style formatting to log warnings to the console (in the browser) or via eprintln!() (if not in the browser).

Structs

• Action
  An action synchronizes an imperative async call to the synchronous reactive system.
• AdditionalAttributes
  A collection of additional HTML attributes to be applied to an element, each of which may or may not be reactive.
• AdditionalAttributesIter
  Iterator over additional HTML attributes.
• AnimatedShowProps
  Props for the AnimatedShow component.
• AnimatedShowPropsBuilder
  Builder for AnimatedShowProps instances.
• AnimationFrameRequestHandle
  Handle that is generated by request_animation_frame_with_handle and can be used to cancel the animation frame request.
• AwaitProps
  Props for the Await component.
• AwaitPropsBuilder
  Builder for AwaitProps instances.
• ErrorBoundaryProps
  Props for the ErrorBoundary component.
• ErrorBoundaryPropsBuilder
  Builder for ErrorBoundaryProps instances.
• Errors
  A struct to hold all the possible errors that could be provided by child Views
• ForProps
  Props for the For component.
• ForPropsBuilder
  Builder for ForProps instances.
• Fragment
  Represents a group of views.
• FragmentData
  Represents its pending <Suspense/> fragment.
• GlobalSuspenseContext
  A single, global suspense context that will be checked when resources are read. This won’t be “blocked” by lower suspense components. This is useful for e.g., holding route transitions.
• HtmlElement
  Represents an HTML element.
• IdleCallbackHandle
  Handle that is generated by request_idle_callback_with_handle and can be used to cancel the idle callback.
• IntervalHandle
  Handle that is generated by set_interval and can be used to clear the interval.
• LeptosOptions
  This struct serves as a convenient place to store details used for configuring Leptos. It’s used in our actix, axum, and viz integrations to generate the correct path for WASM, JS, and Websockets, as well as other configuration tasks. It shares keys with cargo-leptos, to allow for easy interoperability
• MaybeProp
  A wrapping type for an optional component prop, which can either be a signal or a non-reactive value, and which may or may not have a value. In other words, this is an Option<MaybeSignal<Option<T>>> that automatically flattens its getters.
• Memo
  An efficient derived reactive value based on other reactive values.
• MultiAction
  An action that synchronizes multiple imperative async calls to the reactive system, tracking the progress of each one.
• NodeRef
  Contains a shared reference to a DOM node created while using the view macro to create your UI.
• ReadSignal
  The getter for a reactive signal.
• Resource
  A signal that reflects the current state of an asynchronous task, allowing you to integrate async Futures into the synchronous reactive system.
• ResourceId
  Unique ID assigned to a Resource.
• RuntimeId
  Unique ID assigned to a Runtime.
• RwSignal
  A signal that combines the getter and setter into one value, rather than separating them into a ReadSignal and a WriteSignal. You may prefer this its style, or it may be easier to pass around in a context or as a function argument.
• Scope
  A Each scope can have child scopes, and may in turn have a parent.
• ScopeDisposer
  Creating a Scope gives you a disposer, which can be called to dispose of that reactive scope.
• ScopeId
  Unique ID assigned to a Scope.
• ShowProps
  Props for the Show component.
• ShowPropsBuilder
  Builder for ShowProps instances.
• Signal
  A wrapper for any kind of readable reactive signal: a ReadSignal, Memo, RwSignal, or derived signal closure.
• SignalSetter
  A wrapper for any kind of settable reactive signal: a WriteSignal, RwSignal, or closure that receives a value and sets a signal depending on it.
• StoredValue
  A non-reactive wrapper for any value, which can be created with store_value.
• SuspenseContext
  Tracks Resources that are read under a suspense context, i.e., within a Suspense component.
• SuspenseProps
  Props for the Suspense component.
• SuspensePropsBuilder
  Builder for SuspenseProps instances.
• TextProp
  Describes a value that is either a static or a reactive string, i.e., a String, a &str, or a reactive Fn() -> String.
• TimeoutHandle
  Handle that is generated by set_timeout_with_handle and can be used to clear the timeout.
• TransitionProps
  Props for the Transition component.
• TransitionPropsBuilder
  Builder for TransitionProps instances.
• Trigger
  Reactive Trigger, notifies reactive code to rerun.
• WriteSignal
  The setter for a reactive signal.

Enums

• Attribute
  Represents the different possible values an attribute node could have.
• Class
  Represents the different possible values a single class on an element could have, allowing you to do fine-grained updates to single items in Element.classList.
• MaybeSignal
  A wrapper for a value that is either T or Signal<T>.
• Property
  Represents the different possible values an element property could have, allowing you to do fine-grained updates to single fields.
• SerializationError
  Describes errors that can occur while serializing and deserializing data, typically during the process of streaming Resources from the server to the client.
• ServerFnError
  Type for errors that can occur when using server functions.
• ServerFnErrorErr
  Type for errors that can occur when using server functions.
• View
  A leptos view which can be mounted to the DOM.

Traits

• CollectView
  Collects an iterator or collection into a View.
• IntoAttribute
  Converts some type into an Attribute.
• IntoClass
  Converts some type into a Class.
• IntoProperty
  Converts some type into a Property.
• IntoSignal
  Helper trait for converting Fn() -> T closures into Signal<T>.
• IntoSignalSetter
  Helper trait for converting Fn(T) into SignalSetter<T>.
• IntoStyle
  Converts some type into a Style.
• IntoView
  Converts the value into a View.
• Serializable
  Describes an object that can be serialized to or from a supported format Currently those are JSON and Cbor
• ServerFn
  Defines a “server function.” A server function can be called from the server or the client, but the body of its code will only be run on the server, i.e., if a crate feature ssr is enabled.
• SignalDispose
  This trait allows disposing a signal before its Scope has been disposed.
• SignalGet
  This trait allows getting an owned value of the signals inner type.
• SignalGetUntracked
  Trait implemented for all signal types which you can get a value from, such as ReadSignal, Memo, etc., which allows getting the inner value without subscribing to the current scope.
• SignalSet
  This trait allows setting the value of a signal.
• SignalSetUntracked
  Trait implemented for all signal types which you can set the inner value, such as WriteSignal and RwSignal, which allows setting the inner value without causing effects which depend on the signal from being run.
• SignalStream
  This trait allows converting a signal into a async [Stream].
• SignalUpdate
  This trait allows updating the inner value of a signal.
• SignalUpdateUntracked
  This trait allows updating the signals value without causing dependant effects to run.
• SignalWith
  This trait allows obtaining an immutable reference to the signal’s inner type.
• SignalWithUntracked
  This trait allows getting a reference to the signals inner value without creating a dependency on the signal.

Functions

• AnimatedShow
  A component that will show its children when the when condition is true. Additionally, you need to specify a hide_delay. If the when condition changes to false, the unmounting of the children will be delayed by the specified Duration. If you provide the optional show_class and hide_class, you can create very easy mount / unmount animations.
• Await
  Allows you to inline the data loading for an async block or server function directly into your view. This is the equivalent of combining a create_resource that only loads once (i.e., with a source signal || ()) with a Suspense with no fallback. Adding bind:{variable name} to the props makes the data available in the children that variable name, when resolved.
• ErrorBoundary
  When you render a Result<_, _> in your view, in the Err case it will render nothing, and search up through the view tree for an <ErrorBoundary/>. This component lets you define a fallback that should be rendered in that error case, allowing you to handle errors within a section of the interface.
• For
  Iterates over children and displays them, keyed by the key function given. This is much more efficient than naively iterating over nodes with .iter().map(|n| view! { cx, ... })..., as it avoids re-creating DOM nodes that are not being changed.
• Show
  A component that will show its children when the when condition is true, and show the fallback when it is false, without rerendering every time the condition changes. Note: Because of the nature of generic arguments, it’s not really possible to make the fallback optional. If you want an empty fallback state—in other words, if you want to show the children if when is true and noting otherwise—use fallback=|_| () (i.e., a fallback function that returns the unit type ()).
• Suspense
  If any Resources are read in the children of this component, it will show the fallback while they are loading. Once all are resolved, it will render the children. Note that the children will be rendered initially (in order to capture the fact that those resources are read under the suspense), so you cannot assume that resources have Some value in children.
• Transition
  If any Resources are read in the children of this component, it will show the fallback while they are loading. Once all are resolved, it will render the children. Unlike Suspense, this will not fall back to the fallback state if there are further changes after the initial load. Note that the children will be rendered initially (in order to capture the fact that those resources are read under the suspense), so you cannot assume that resources have Some value in children.
• create_action
  Creates an Action to synchronize an imperative async call to the synchronous reactive system.
• create_blocking_resource
  Creates a “blocking” Resource. When server-side rendering is used, this resource will cause any <Suspense/> you read it under to block the initial chunk of HTML from being sent to the client. This means that if you set things like HTTP headers or <head> metadata in that <Suspense/>, that header material will be included in the server’s original response.
• create_effect
  Effects run a certain chunk of code whenever the signals they depend on change. create_effect immediately runs the given function once, tracks its dependence on any signal values read within it, and reruns the function whenever the value of a dependency changes.
• create_isomorphic_effect
  Creates an effect; unlike effects created by create_effect, isomorphic effects will run on the server as well as the client.
• create_local_resource
  Creates a local Resource, which is a signal that reflects the current state of an asynchronous task, allowing you to integrate async Futures into the synchronous reactive system.
• create_local_resource_with_initial_value
  Creates a local Resource with the given initial value, which will only generate and run a Future using the fetcher when the source changes.
• create_many_signals
  Works exactly as create_signal, but creates multiple signals at once.
• create_many_signals_mapped
  Works exactly as create_many_signals, but applies the map function to each signal pair.
• create_memo
  Creates an efficient derived reactive value based on other reactive values.
• create_multi_action
  Creates an MultiAction to synchronize an imperative async call to the synchronous reactive system.
• create_node_ref
  Creates a shared reference to a DOM node created while using the view macro to create your UI.
• create_read_slice
  Takes a memoized, read-only slice of a signal. This is equivalent to the read-only half of create_slice.
• create_resource
  Creates a Resource, which is a signal that reflects the current state of an asynchronous task, allowing you to integrate async Futures into the synchronous reactive system.
• create_resource_with_initial_value
  Creates a Resource with the given initial value, which will only generate and run a Future using the fetcher when the source changes.
• create_rw_signal
  Creates a reactive signal with the getter and setter unified in one value. You may prefer this style, or it may be easier to pass around in a context or as a function argument.
• create_selector
  Creates a conditional signal that only notifies subscribers when a change in the source signal’s value changes whether it is equal to the key value (as determined by PartialEq.)
• create_selector_with_fn
  Creates a conditional signal that only notifies subscribers when a change in the source signal’s value changes whether the given function is true.
• create_server_action
  Creates an Action that can be used to call a server function.
• create_server_multi_action
  Creates an MultiAction that can be used to call a server function.
• create_signal
  Creates a signal, the basic reactive primitive.
• create_signal_from_stream
  Creates a signal that always contains the most recent value emitted by a Stream. If the stream has not yet emitted a value since the signal was created, the signal’s value will be None.
• create_slice
  Derives a reactive slice of an RwSignal.
• create_trigger
  Creates a Trigger, a kind of reactive primitive.
• create_write_slice
  Creates a setter to access one slice of a signal. This is equivalent to the write-only half of create_slice.
• debounce
  “Debounce” a callback function. This will cause it to wait for a period of delay after it is called. If it is called again during that period, it will wait delay before running, and so on. This can be used, for example, to wrap event listeners to prevent them from firing constantly as you type.
• document
  Returns the Document.
• event_target
  Helper function to extract Event.target from any event.
• event_target_checked
  Helper function to extract event.target.checked from an event.
• event_target_value
  Helper function to extract event.target.value from an event.
• expect_context
  Extracts a context value of type T from the reactive system by traversing it upwards, beginning from the current Scope and iterating through its parents, if any. The context value should have been provided elsewhere using provide_context.
• get_configuration
  Loads LeptosOptions from a Cargo.toml with layered overrides. If an env var is specified, like LEPTOS_ENV, it will override a setting in the file. It takes in an optional path to a Cargo.toml file. If None is provided, you’ll need to set the options as environment variables or rely on the defaults. This is the preferred approach for cargo-leptos. If Some(“./Cargo.toml”) is provided, Leptos will read in the settings itself. This option currently does not allow dashes in file or folder names, as all dashes become underscores
• get_property
  Gets the value of a property set on a DOM element.
• location
  Returns the current window.location.
• location_hash
  Current window.location.hash without the beginning #.
• location_pathname
  Current window.location.pathname.
• mount_to
  Runs the provided closure and mounts the result to the provided element.
• mount_to_body
  Runs the provided closure and mounts the result to the <body>.
• on_cleanup
  Creates a cleanup function, which will be run when a Scope is disposed.
• provide_context
  Provides a context value of type T to the current reactive Scope and all of its descendants. This can be consumed using use_context.
• queue_microtask
  The microtask is a short function which will run after the current task has completed its work and when there is no other code waiting to be run before control of the execution context is returned to the browser’s event loop.
• request_animation_frame
  Runs the given function between the next repaint using Window.requestAnimationFrame.
• request_animation_frame_with_handle
  Runs the given function between the next repaint using Window.requestAnimationFrame, returning a cancelable handle.
• request_idle_callback
  Queues the given function during an idle period using Window.requestIdleCallback.
• request_idle_callback_with_handle
  Queues the given function during an idle period using Window.requestIdleCallback, returning a cancelable handle.
• set_interval
  Repeatedly calls the given function, with a delay of the given duration between calls. See setInterval().
• set_interval_with_handle
  Repeatedly calls the given function, with a delay of the given duration between calls, returning a cancelable handle. See setInterval().
• set_property
  Sets a property on a DOM element.
• set_timeout
  Executes the given function after the given duration of time has passed. setTimeout().
• set_timeout_with_handle
  Executes the given function after the given duration of time has passed, returning a cancelable handle. setTimeout().
• spawn_local
  Spawns and runs a thread-local Future in a platform-independent way.
• store_value
  Creates a non-reactive wrapper for any value by storing it within the reactive system.
• use_context
  Extracts a context value of type T from the reactive system by traversing it upwards, beginning from the current Scope and iterating through its parents, if any. The context value should have been provided elsewhere using provide_context.
• watch
  A version of create_effect that listens to any dependency that is accessed inside deps and returns a stop handler. The return value of deps is passed into callback as an argument together with the previous value. Additionally the last return value of callback is provided as a third argument as is done in create_effect.
• window
  Returns the Window.
• window_event_listener
  Creates a window event listener from a typed event.
• window_event_listener_untyped
  Adds an event listener to the Window, typed as a generic Event.

Type Definitions

• AttributeValue
  A type for taking anything that implements IntoAttribute.
• Children
  The most common type for the children property on components, which can only be called once.
• ChildrenFn
  A type for the children property on components that can be called more than once.
• ChildrenFnMut
  A type for the children property on components that can be called more than once, but may mutate the children.

Attribute Macros

• component
  Annotates a function so that it can be used with your template as a Leptos <Component/>.
• server
  Declares that a function is a server function. This means that its body will only run on the server, i.e., when the ssr feature is enabled.
• slot
  Annotates a struct so that it can be used with your Component as a slot.

Derive Macros

• Params
  Derives a trait that parses a map of string keys and values into a typed data structure, e.g., for route params.